<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html 
     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>Module: Spec::Matchers</title>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta http-equiv="Content-Script-Type" content="text/javascript" />
  <link rel="stylesheet" href="../.././rdoc-style.css" type="text/css" media="screen" />
  <script type="text/javascript">
  // <![CDATA[

  function popupCode( url ) {
    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
  }

  function toggleCode( id ) {
    if ( document.getElementById )
      elem = document.getElementById( id );
    else if ( document.all )
      elem = eval( "document.all." + id );
    else
      return false;

    elemStyle = elem.style;
    
    if ( elemStyle.display != "block" ) {
      elemStyle.display = "block"
    } else {
      elemStyle.display = "none"
    }

    return true;
  }
  
  // Make codeblocks hidden by default
  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
  
  // ]]>
  </script>

</head>
<body>



    <div id="classHeader">
        <table class="header-table">
        <tr class="top-aligned-row">
          <td><strong>Module</strong></td>
          <td class="class-name-in-header">Spec::Matchers</td>
        </tr>
        <tr class="top-aligned-row">
            <td><strong>In:</strong></td>
            <td>
                <a href="../../files/vendor/plugins/rspec/lib/spec/matchers_rb.html">
                vendor/plugins/rspec/lib/spec/matchers.rb
                </a>
        <br />
                <a href="../../files/vendor/plugins/rspec/lib/spec/matchers/raise_error_rb.html">
                vendor/plugins/rspec/lib/spec/matchers/raise_error.rb
                </a>
        <br />
                <a href="../../files/vendor/plugins/rspec/lib/spec/matchers/eql_rb.html">
                vendor/plugins/rspec/lib/spec/matchers/eql.rb
                </a>
        <br />
                <a href="../../files/vendor/plugins/rspec/lib/spec/matchers/match_rb.html">
                vendor/plugins/rspec/lib/spec/matchers/match.rb
                </a>
        <br />
                <a href="../../files/vendor/plugins/rspec/lib/spec/matchers/simple_matcher_rb.html">
                vendor/plugins/rspec/lib/spec/matchers/simple_matcher.rb
                </a>
        <br />
                <a href="../../files/vendor/plugins/rspec/lib/spec/matchers/be_close_rb.html">
                vendor/plugins/rspec/lib/spec/matchers/be_close.rb
                </a>
        <br />
                <a href="../../files/vendor/plugins/rspec/lib/spec/matchers/throw_symbol_rb.html">
                vendor/plugins/rspec/lib/spec/matchers/throw_symbol.rb
                </a>
        <br />
                <a href="../../files/vendor/plugins/rspec/lib/spec/matchers/change_rb.html">
                vendor/plugins/rspec/lib/spec/matchers/change.rb
                </a>
        <br />
                <a href="../../files/vendor/plugins/rspec/lib/spec/matchers/exist_rb.html">
                vendor/plugins/rspec/lib/spec/matchers/exist.rb
                </a>
        <br />
                <a href="../../files/vendor/plugins/rspec/lib/spec/matchers/respond_to_rb.html">
                vendor/plugins/rspec/lib/spec/matchers/respond_to.rb
                </a>
        <br />
                <a href="../../files/vendor/plugins/rspec/lib/spec/matchers/equal_rb.html">
                vendor/plugins/rspec/lib/spec/matchers/equal.rb
                </a>
        <br />
                <a href="../../files/vendor/plugins/rspec/lib/spec/matchers/have_rb.html">
                vendor/plugins/rspec/lib/spec/matchers/have.rb
                </a>
        <br />
                <a href="../../files/vendor/plugins/rspec/lib/spec/matchers/be_rb.html">
                vendor/plugins/rspec/lib/spec/matchers/be.rb
                </a>
        <br />
                <a href="../../files/vendor/plugins/rspec/lib/spec/matchers/satisfy_rb.html">
                vendor/plugins/rspec/lib/spec/matchers/satisfy.rb
                </a>
        <br />
                <a href="../../files/vendor/plugins/rspec/lib/spec/matchers/has_rb.html">
                vendor/plugins/rspec/lib/spec/matchers/has.rb
                </a>
        <br />
                <a href="../../files/vendor/plugins/rspec/lib/spec/matchers/operator_matcher_rb.html">
                vendor/plugins/rspec/lib/spec/matchers/operator_matcher.rb
                </a>
        <br />
                <a href="../../files/vendor/plugins/rspec/lib/spec/matchers/include_rb.html">
                vendor/plugins/rspec/lib/spec/matchers/include.rb
                </a>
        <br />
            </td>
        </tr>

        </table>
    </div>
  <!-- banner header -->

  <div id="bodyContent">



  <div id="contextContent">

    <div id="description">
      <p>
RSpec ships with a number of useful Expression <a
href="Matchers.html">Matchers</a>. An Expression Matcher is any object that
responds to the following methods:
</p>
<pre>
  matches?(actual)
  failure_message
  negative_failure_message #optional
  description #optional
</pre>
<p>
See <a href="Expectations.html">Spec::Expectations</a> to learn how to use
these as Expectation <a href="Matchers.html">Matchers</a>. See <a
href="Mocks.html">Spec::Mocks</a> to learn how to use them as Mock Argument
Constraints.
</p>
<h2>Predicates</h2>
<p>
In addition to those Expression <a href="Matchers.html">Matchers</a> that
are defined explicitly, RSpec will create custom <a
href="Matchers.html">Matchers</a> on the fly for any arbitrary predicate,
giving your specs a much more natural language feel.
</p>
<p>
A Ruby predicate is a method that ends with a &quot;?&quot; and returns
true or false. Common examples are +empty?+, +nil?+, and +instance_of?+.
</p>
<p>
All you need to do is write +should be_+ followed by the predicate without
the question mark, and RSpec will figure it out from there. For example:
</p>
<pre>
  [].should be_empty =&gt; [].empty? #passes
  [].should_not be_empty =&gt; [].empty? #fails
</pre>
<p>
In addtion to prefixing the predicate matchers with &quot;be_&quot;, you
can also use &quot;be_a_&quot; and &quot;be_an_&quot;, making your specs
read much more naturally:
</p>
<pre>
  &quot;a string&quot;.should be_an_instance_of(String) =&gt;&quot;a string&quot;.instance_of?(String) #passes

  3.should be_a_kind_of(Fixnum) =&gt; 3.kind_of?(Numeric) #passes
  3.should be_a_kind_of(Numeric) =&gt; 3.kind_of?(Numeric) #passes
  3.should be_an_instance_of(Fixnum) =&gt; 3.instance_of?(Fixnum) #passes
  3.should_not be_instance_of(Numeric) =&gt; 3.instance_of?(Numeric) #fails
</pre>
<p>
RSpec will also create custom matchers for predicates like +has_key?+. To
use this feature, just state that the object should have_key(:key) and
RSpec will call has_key?(:key) on the target. For example:
</p>
<pre>
  {:a =&gt; &quot;A&quot;}.should have_key(:a) =&gt; {:a =&gt; &quot;A&quot;}.has_key?(:a) #passes
  {:a =&gt; &quot;A&quot;}.should have_key(:b) =&gt; {:a =&gt; &quot;A&quot;}.has_key?(:b) #fails
</pre>
<p>
You can use this feature to invoke any predicate that begins with
&quot;has_&quot;, whether it is part of the Ruby libraries (like
+Hash#has_key?+) or a method you wrote on your own class.
</p>
<h2>Custom Expectation <a href="Matchers.html">Matchers</a></h2>
<p>
When you find that none of the stock Expectation <a
href="Matchers.html">Matchers</a> provide a natural feeling expectation,
you can very easily write your own.
</p>
<p>
For example, imagine that you are writing a game in which players can <a
href="Matchers.html#M000383">be</a> in various zones on a virtual board. To
specify that bob should <a href="Matchers.html#M000383">be</a> in zone 4,
you could say:
</p>
<pre>
  bob.current_zone.should eql(Zone.new(&quot;4&quot;))
</pre>
<p>
But you might find it more expressive to say:
</p>
<pre>
  bob.should be_in_zone(&quot;4&quot;)
</pre>
<p>
and/or
</p>
<pre>
  bob.should_not be_in_zone(&quot;3&quot;)
</pre>
<p>
To do this, you would need to write a class like this:
</p>
<pre>
  class BeInZone
    def initialize(expected)
      @expected = expected
    end
    def matches?(target)
      @target = target
      @target.current_zone.eql?(Zone.new(@expected))
    end
    def failure_message
      &quot;expected #{@target.inspect} to be in Zone #{@expected}&quot;
    end
    def negative_failure_message
      &quot;expected #{@target.inspect} not to be in Zone #{@expected}&quot;
    end
  end
</pre>
<p>
&#8230; and a method like this:
</p>
<pre>
  def be_in_zone(expected)
    BeInZone.new(expected)
  end
</pre>
<p>
And then expose the method to your specs. This is normally done by
including the method and the class in a module, which is then included in
your spec:
</p>
<pre>
  module CustomGameMatchers
    class BeInZone
      ...
    end

    def be_in_zone(expected)
      ...
    end
  end

  describe &quot;Player behaviour&quot; do
    include CustomGameMatchers
    ...
  end
</pre>
<p>
or you can <a href="Matchers.html#M000385">include</a> in globally in a
spec_helper.rb file <tt>require</tt>d from your spec file(s):
</p>
<pre>
  Spec::Runner.configure do |config|
    config.include(CustomGameMatchers)
  end
</pre>

    </div>


   </div>

    <div id="method-list">
      <h3 class="section-bar">Methods</h3>

      <div class="name-list">
      <a href="#M000383">be</a>&nbsp;&nbsp;
      <a href="#M000373">be_close</a>&nbsp;&nbsp;
      <a href="#M000375">change</a>&nbsp;&nbsp;
      <a href="#M000370">eql</a>&nbsp;&nbsp;
      <a href="#M000378">equal</a>&nbsp;&nbsp;
      <a href="#M000376">exist</a>&nbsp;&nbsp;
      <a href="#M000379">have</a>&nbsp;&nbsp;
      <a href="#M000381">have_at_least</a>&nbsp;&nbsp;
      <a href="#M000382">have_at_most</a>&nbsp;&nbsp;
      <a href="#M000380">have_exactly</a>&nbsp;&nbsp;
      <a href="#M000385">include</a>&nbsp;&nbsp;
      <a href="#M000371">match</a>&nbsp;&nbsp;
      <a href="#M000369">raise_error</a>&nbsp;&nbsp;
      <a href="#M000377">respond_to</a>&nbsp;&nbsp;
      <a href="#M000384">satisfy</a>&nbsp;&nbsp;
      <a href="#M000372">simple_matcher</a>&nbsp;&nbsp;
      <a href="#M000374">throw_symbol</a>&nbsp;&nbsp;
      </div>
    </div>

  </div>


    <!-- if includes -->

    <div id="section">

    <div id="class-list">
      <h3 class="section-bar">Classes and Modules</h3>

      Module <a href="Matchers/ModuleMethods.html" class="link">Spec::Matchers::ModuleMethods</a><br />
Class <a href="Matchers/BaseOperatorMatcher.html" class="link">Spec::Matchers::BaseOperatorMatcher</a><br />
Class <a href="Matchers/Exist.html" class="link">Spec::Matchers::Exist</a><br />
Class <a href="Matchers/MatcherError.html" class="link">Spec::Matchers::MatcherError</a><br />
Class <a href="Matchers/SimpleMatcher.html" class="link">Spec::Matchers::SimpleMatcher</a><br />

    </div>




      


    <!-- if method_list -->
    <div id="methods">
      <h3 class="section-bar">Public Instance methods</h3>

      <div id="method-M000383" class="method-detail">
        <a name="M000383"></a>

        <div class="method-heading">
          <a href="#M000383" class="method-signature">
          <span class="method-name">should be<br />
should be_true<br />
should be_false<br />
should be_nil<br />
should be_arbitrary_predicate(*args)<br />
should_not be_nil<br />
should_not be_arbitrary_predicate(*args)<br />
</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Given true, false, or nil, will pass if given value is true, false or nil
(respectively). Given no args means the caller should <a
href="Matchers.html#M000384">satisfy</a> an if condition (to <a
href="Matchers.html#M000383">be</a> or not to <a
href="Matchers.html#M000383">be</a>).
</p>
<p>
Predicates are any Ruby method that ends in a &quot;?&quot; and returns
true or false. Given be_ followed by arbitrary_predicate (without the
&quot;?&quot;), RSpec will <a href="Matchers.html#M000371">match</a>
convert that into a query against the target object.
</p>
<p>
The arbitrary_predicate feature will handle any predicate prefixed with
&quot;be_an_&quot; (e.g. be_an_instance_of), &quot;be_a_&quot; (e.g.
be_a_kind_of) or &quot;be_&quot; (e.g. be_empty), letting you choose the
prefix that best suits the predicate.
</p>
<h2>Examples</h2>
<pre>
  target.should be
  target.should be_true
  target.should be_false
  target.should be_nil
  target.should_not be_nil

  collection.should be_empty #passes if target.empty?
  &quot;this string&quot;.should be_an_intance_of(String)

  target.should_not be_empty #passes unless target.empty?
  target.should_not be_old_enough(16) #passes unless target.old_enough?(16)
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000383-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000383-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/rspec/lib/spec/matchers/be.rb, line 217</span>
217:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">be</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">args</span>)
218:       <span class="ruby-constant">Matchers</span><span class="ruby-operator">::</span><span class="ruby-constant">Be</span>.<span class="ruby-identifier">new</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">args</span>)
219:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000373" class="method-detail">
        <a name="M000373"></a>

        <div class="method-heading">
          <a href="#M000373" class="method-signature">
          <span class="method-name">should be_close(expected, delta)<br />
should_not be_close(expected, delta)<br />
</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Passes if given == expected +/- delta
</p>
<h2><a href="Example.html">Example</a></h2>
<pre>
  result.should be_close(3.0, 0.5)
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000373-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000373-source">
<pre>
    <span class="ruby-comment cmt"># File vendor/plugins/rspec/lib/spec/matchers/be_close.rb, line 33</span>
33:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">be_close</span>(<span class="ruby-identifier">expected</span>, <span class="ruby-identifier">delta</span>)
34:       <span class="ruby-constant">Matchers</span><span class="ruby-operator">::</span><span class="ruby-constant">BeClose</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">expected</span>, <span class="ruby-identifier">delta</span>)
35:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000375" class="method-detail">
        <a name="M000375"></a>

        <div class="method-heading">
          <a href="#M000375" class="method-signature">
          <span class="method-name">should change(receiver, message, &block)<br />
should change(receiver, message, &block).by(value)<br />
should change(receiver, message, &block).from(old).to(new)<br />
should_not change(receiver, message, &block)<br />
</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Allows you to specify that a Proc will cause some value to <a
href="Matchers.html#M000375">change</a>.
</p>
<h2>Examples</h2>
<pre>
  lambda {
    team.add_player(player)
  }.should change(roster, :count)

  lambda {
    team.add_player(player)
  }.should change(roster, :count).by(1)

  lambda {
    team.add_player(player)
  }.should change(roster, :count).by_at_least(1)

  lambda {
    team.add_player(player)
  }.should change(roster, :count).by_at_most(1)

  string = &quot;string&quot;
  lambda {
    string.reverse!
  }.should change { string }.from(&quot;string&quot;).to(&quot;gnirts&quot;)

  lambda {
    person.happy_birthday
  }.should change(person, :birthday).from(32).to(33)

  lambda {
    employee.develop_great_new_social_networking_app
  }.should change(employee, :title).from(&quot;Mail Clerk&quot;).to(&quot;CEO&quot;)
</pre>
<p>
Evaluates <tt>receiver.message</tt> or <tt>block</tt> before and after it
evaluates the c object (generated by the lambdas in the examples above).
</p>
<p>
Then compares the values before and after the <tt>receiver.message</tt> and
evaluates the difference compared to the expected difference.
</p>
<h2>WARNING</h2>
<p>
<tt>should_not <a href="Matchers.html#M000375">change</a></tt> only
supports the form with no subsequent calls to <tt>by</tt>,
<tt>by_at_least</tt>, <tt>by_at_most</tt>, <tt>to</tt> or <tt>from</tt>.
</p>
<p>
blocks passed to <tt>should</tt> <tt><a
href="Matchers.html#M000375">change</a></tt> and <tt>should_not</tt> <tt><a
href="Matchers.html#M000375">change</a></tt> must use the <tt>{}</tt> form
(<tt>do/end</tt> is not supported).
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000375-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000375-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/rspec/lib/spec/matchers/change.rb, line 145</span>
145:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">change</span>(<span class="ruby-identifier">receiver</span>=<span class="ruby-keyword kw">nil</span>, <span class="ruby-identifier">message</span>=<span class="ruby-keyword kw">nil</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span>)
146:       <span class="ruby-constant">Matchers</span><span class="ruby-operator">::</span><span class="ruby-constant">Change</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">receiver</span>, <span class="ruby-identifier">message</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span>)
147:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000370" class="method-detail">
        <a name="M000370"></a>

        <div class="method-heading">
          <a href="#M000370" class="method-signature">
          <span class="method-name">should eql(expected)<br />
should_not eql(expected)<br />
</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Passes if given and expected are of <a
href="Matchers.html#M000378">equal</a> value, but not necessarily the same
object.
</p>
<p>
See <a
href="http://www.ruby-doc.org/core/classes/Object.html#M001057">www.ruby-doc.org/core/classes/Object.html#M001057</a>
for more information about equality in Ruby.
</p>
<h2>Examples</h2>
<pre>
  5.should eql(5)
  5.should_not eql(3)
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000370-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000370-source">
<pre>
    <span class="ruby-comment cmt"># File vendor/plugins/rspec/lib/spec/matchers/eql.rb, line 39</span>
39:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">eql</span>(<span class="ruby-identifier">expected</span>)
40:       <span class="ruby-constant">Matchers</span><span class="ruby-operator">::</span><span class="ruby-constant">Eql</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">expected</span>)
41:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000378" class="method-detail">
        <a name="M000378"></a>

        <div class="method-heading">
          <a href="#M000378" class="method-signature">
          <span class="method-name">should equal(expected)<br />
should_not equal(expected)<br />
</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Passes if given and expected are the same object (object identity).
</p>
<p>
See <a
href="http://www.ruby-doc.org/core/classes/Object.html#M001057">www.ruby-doc.org/core/classes/Object.html#M001057</a>
for more information about equality in Ruby.
</p>
<h2>Examples</h2>
<pre>
  5.should equal(5) #Fixnums are equal
  &quot;5&quot;.should_not equal(&quot;5&quot;) #Strings that look the same are not the same object
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000378-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000378-source">
<pre>
    <span class="ruby-comment cmt"># File vendor/plugins/rspec/lib/spec/matchers/equal.rb, line 39</span>
39:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">equal</span>(<span class="ruby-identifier">expected</span>)
40:       <span class="ruby-constant">Matchers</span><span class="ruby-operator">::</span><span class="ruby-constant">Equal</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">expected</span>)
41:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000376" class="method-detail">
        <a name="M000376"></a>

        <div class="method-heading">
          <a href="#M000376" class="method-signature">
          <span class="method-name">should exist<br />
should_not exist<br />
</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Passes if given.exist?
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000376-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000376-source">
<pre>
    <span class="ruby-comment cmt"># File vendor/plugins/rspec/lib/spec/matchers/exist.rb, line 20</span>
20:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">exist</span>; <span class="ruby-constant">Exist</span>.<span class="ruby-identifier">new</span>; <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000379" class="method-detail">
        <a name="M000379"></a>

        <div class="method-heading">
          <a href="#M000379" class="method-signature">
          <span class="method-name">should have(number).named_collection__or__sugar<br />
should_not have(number).named_collection__or__sugar<br />
</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Passes if receiver is a collection with the submitted number of items OR if
the receiver OWNS a collection with the submitted number of items.
</p>
<p>
If the receiver OWNS the collection, you must use the name of the
collection. So if a <tt>Team</tt> instance has a collection named
<tt>players</tt>, you must use that name to set the expectation.
</p>
<p>
If the receiver IS the collection, you can use any name you like for
<tt>named_collection</tt>. We&#8216;d recommend using either
&quot;elements&quot;, &quot;members&quot;, or &quot;items&quot; as these
are all standard ways of describing the things IN a collection.
</p>
<p>
This also works for Strings, letting you set an expectation about its
length
</p>
<h2>Examples</h2>
<pre>
  # Passes if team.players.size == 11
  team.should have(11).players

  # Passes if [1,2,3].length == 3
  [1,2,3].should have(3).items #&quot;items&quot; is pure sugar

  # Passes if &quot;this string&quot;.length == 11
  &quot;this string&quot;.should have(11).characters #&quot;characters&quot; is pure sugar
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000379-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000379-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/rspec/lib/spec/matchers/have.rb, line 123</span>
123:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">have</span>(<span class="ruby-identifier">n</span>)
124:       <span class="ruby-constant">Matchers</span><span class="ruby-operator">::</span><span class="ruby-constant">Have</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">n</span>)
125:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000381" class="method-detail">
        <a name="M000381"></a>

        <div class="method-heading">
          <a href="#M000381" class="method-signature">
          <span class="method-name">should have_at_least(number).items<br />
</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Exactly like <a href="Matchers.html#M000379">have</a>() with &gt;=.
</p>
<h2>Warning</h2>
<p>
<tt>should_not</tt> <tt><a
href="Matchers.html#M000381">have_at_least</a></tt> is not supported
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000381-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000381-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/rspec/lib/spec/matchers/have.rb, line 136</span>
136:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">have_at_least</span>(<span class="ruby-identifier">n</span>)
137:       <span class="ruby-constant">Matchers</span><span class="ruby-operator">::</span><span class="ruby-constant">Have</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">n</span>, <span class="ruby-identifier">:at_least</span>)
138:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000382" class="method-detail">
        <a name="M000382"></a>

        <div class="method-heading">
          <a href="#M000382" class="method-signature">
          <span class="method-name">should have_at_most(number).items<br />
</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Exactly like <a href="Matchers.html#M000379">have</a>() with &lt;=.
</p>
<h2>Warning</h2>
<p>
<tt>should_not</tt> <tt><a
href="Matchers.html#M000382">have_at_most</a></tt> is not supported
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000382-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000382-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/rspec/lib/spec/matchers/have.rb, line 148</span>
148:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">have_at_most</span>(<span class="ruby-identifier">n</span>)
149:       <span class="ruby-constant">Matchers</span><span class="ruby-operator">::</span><span class="ruby-constant">Have</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">n</span>, <span class="ruby-identifier">:at_most</span>)
150:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000380" class="method-detail">
        <a name="M000380"></a>

        <div class="method-heading">
          <span class="method-name">have_exactly</span><span class="method-args">(n)</span>
        </div>
      
        <div class="method-description">
          <p>
Alias for <a href="Matchers.html#M000379">have</a>
</p>
        </div>
      </div>

      <div id="method-M000385" class="method-detail">
        <a name="M000385"></a>

        <div class="method-heading">
          <a href="#M000385" class="method-signature">
          <span class="method-name">should include(expected)<br />
should_not include(expected)<br />
</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Passes if given includes expected. This works for collections and Strings.
You can also pass in multiple args and it will only pass if all args are
found in collection.
</p>
<h2>Examples</h2>
<pre>
  [1,2,3].should include(3)
  [1,2,3].should include(2,3) #would pass
  [1,2,3].should include(2,3,4) #would fail
  [1,2,3].should_not include(4)
  &quot;spread&quot;.should include(&quot;read&quot;)
  &quot;spread&quot;.should_not include(&quot;red&quot;)
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000385-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000385-source">
<pre>
    <span class="ruby-comment cmt"># File vendor/plugins/rspec/lib/spec/matchers/include.rb, line 66</span>
66:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">include</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">expected</span>)
67:       <span class="ruby-constant">Matchers</span><span class="ruby-operator">::</span><span class="ruby-constant">Include</span>.<span class="ruby-identifier">new</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">expected</span>)
68:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000371" class="method-detail">
        <a name="M000371"></a>

        <div class="method-heading">
          <a href="#M000371" class="method-signature">
          <span class="method-name">should match(regexp)<br />
should_not match(regexp)<br />
</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Given a <a href="../Regexp.html">Regexp</a>, passes if given =~ regexp
</p>
<h2>Examples</h2>
<pre>
  email.should match(/^([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})$/i)
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000371-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000371-source">
<pre>
    <span class="ruby-comment cmt"># File vendor/plugins/rspec/lib/spec/matchers/match.rb, line 37</span>
37:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">match</span>(<span class="ruby-identifier">regexp</span>)
38:       <span class="ruby-constant">Matchers</span><span class="ruby-operator">::</span><span class="ruby-constant">Match</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">regexp</span>)
39:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000369" class="method-detail">
        <a name="M000369"></a>

        <div class="method-heading">
          <a href="#M000369" class="method-signature">
          <span class="method-name">should raise_error()<br />
should raise_error(NamedError)<br />
should raise_error(NamedError, String)<br />
should raise_error(NamedError, Regexp)<br />
should raise_error() { |error| ... }<br />
should raise_error(NamedError) { |error| ... }<br />
should raise_error(NamedError, String) { |error| ... }<br />
should raise_error(NamedError, Regexp) { |error| ... }<br />
should_not raise_error()<br />
should_not raise_error(NamedError)<br />
should_not raise_error(NamedError, String)<br />
should_not raise_error(NamedError, Regexp)<br />
</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
With no args, matches if any error is raised. With a named error, matches
only if that specific error is raised. With a named error and messsage
specified as a <a href="../String.html">String</a>, matches only if both <a
href="Matchers.html#M000371">match</a>. With a named error and messsage
specified as a <a href="../Regexp.html">Regexp</a>, matches only if both <a
href="Matchers.html#M000371">match</a>. Pass an optional block to perform
extra verifications on the exception matched
</p>
<h2>Examples</h2>
<pre>
  lambda { do_something_risky }.should raise_error
  lambda { do_something_risky }.should raise_error(PoorRiskDecisionError)
  lambda { do_something_risky }.should raise_error(PoorRiskDecisionError) { |error| error.data.should == 42 }
  lambda { do_something_risky }.should raise_error(PoorRiskDecisionError, &quot;that was too risky&quot;)
  lambda { do_something_risky }.should raise_error(PoorRiskDecisionError, /oo ri/)

  lambda { do_something_risky }.should_not raise_error
  lambda { do_something_risky }.should_not raise_error(PoorRiskDecisionError)
  lambda { do_something_risky }.should_not raise_error(PoorRiskDecisionError, &quot;that was too risky&quot;)
  lambda { do_something_risky }.should_not raise_error(PoorRiskDecisionError, /oo ri/)
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000369-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000369-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/rspec/lib/spec/matchers/raise_error.rb, line 128</span>
128:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">raise_error</span>(<span class="ruby-identifier">error</span>=<span class="ruby-constant">Exception</span>, <span class="ruby-identifier">message</span>=<span class="ruby-keyword kw">nil</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span>)
129:       <span class="ruby-constant">Matchers</span><span class="ruby-operator">::</span><span class="ruby-constant">RaiseError</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">error</span>, <span class="ruby-identifier">message</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span>)
130:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000377" class="method-detail">
        <a name="M000377"></a>

        <div class="method-heading">
          <a href="#M000377" class="method-signature">
          <span class="method-name">should respond_to(*names)<br />
should_not respond_to(*names)<br />
</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Matches if the target object responds to all of the names provided. Names
can <a href="Matchers.html#M000383">be</a> Strings or Symbols.
</p>
<h2>Examples</h2>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000377-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000377-source">
<pre>
    <span class="ruby-comment cmt"># File vendor/plugins/rspec/lib/spec/matchers/respond_to.rb, line 42</span>
42:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">respond_to</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">names</span>)
43:       <span class="ruby-constant">Matchers</span><span class="ruby-operator">::</span><span class="ruby-constant">RespondTo</span>.<span class="ruby-identifier">new</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">names</span>)
44:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000384" class="method-detail">
        <a name="M000384"></a>

        <div class="method-heading">
          <a href="#M000384" class="method-signature">
          <span class="method-name">should satisfy {}<br />
should_not satisfy {}<br />
</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Passes if the submitted block returns true. Yields target to the block.
</p>
<p>
Generally speaking, this should <a href="Matchers.html#M000383">be</a>
thought of as a last resort when you can&#8216;t find any other way to
specify the behaviour you wish to specify.
</p>
<p>
If you do find yourself in such a situation, you could always write a
custom matcher, which would likely make your specs more expressive.
</p>
<h2>Examples</h2>
<pre>
  5.should satisfy { |n|
    n &gt; 3
  }
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000384-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000384-source">
<pre>
    <span class="ruby-comment cmt"># File vendor/plugins/rspec/lib/spec/matchers/satisfy.rb, line 43</span>
43:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">satisfy</span>(<span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span>)
44:       <span class="ruby-constant">Matchers</span><span class="ruby-operator">::</span><span class="ruby-constant">Satisfy</span>.<span class="ruby-identifier">new</span>(<span class="ruby-operator">&amp;</span><span class="ruby-identifier">block</span>)
45:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000372" class="method-detail">
        <a name="M000372"></a>

        <div class="method-heading">
          <a href="#M000372" class="method-signature">
          <span class="method-name">simple_matcher</span><span class="method-args">(description=nil, &amp;match_block)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
<a href="Matchers.html#M000372">simple_matcher</a> makes it easy for you to
create your own custom matchers in just a few lines of code when you
don&#8216;t need all the power of a completely custom matcher object.
</p>
<p>
The <tt>description</tt> argument will appear as part of any failure
message, and is also the source for auto-generated descriptions.
</p>
<p>
The <tt>match_block</tt> can <a href="Matchers.html#M000379">have</a> an
arity of 1 or 2. The first block argument will <a
href="Matchers.html#M000383">be</a> the given value. The second, if the
block accepts it will <a href="Matchers.html#M000383">be</a> the matcher
itself, giving you access to set custom failure messages in favor of the
defaults.
</p>
<p>
The <tt>match_block</tt> should return a boolean: <tt>true</tt> indicates a
<a href="Matchers.html#M000371">match</a>, which will pass if you use
<tt>should</tt> and fail if you use <tt>should_not</tt>. false (or nil)
indicates no <a href="Matchers.html#M000371">match</a>, which will do the
reverse: fail if you use <tt>should</tt> and pass if you use
<tt>should_not</tt>.
</p>
<p>
An error in the <tt>match_block</tt> will bubble up, resulting in a
failure.
</p>
<h2><a href="Example.html">Example</a> with default messages</h2>
<pre>
  def be_even
    simple_matcher(&quot;an even number&quot;) { |given| given % 2 == 0 }
  end

  describe 2 do
    it &quot;should be even&quot; do
      2.should be_even
    end
  end
</pre>
<p>
Given an odd number, this example would produce an error message stating:
expected &quot;an even number&quot;, got 3.
</p>
<p>
Unfortunately, if you&#8216;re a fan of auto-generated descriptions, this
will produce &quot;should an even number.&quot; Not the most desirable
result. You can control that using custom messages:
</p>
<h2><a href="Example.html">Example</a> with custom messages</h2>
<pre>
  def rhyme_with(expected)
    simple_matcher(&quot;rhyme with #{expected.inspect}&quot;) do |given, matcher|
      matcher.failure_message = &quot;expected #{given.inspect} to rhyme with #{expected.inspect}&quot;
      matcher.negative_failure_message = &quot;expected #{given.inspect} not to rhyme with #{expected.inspect}&quot;
      given.rhymes_with? expected
    end
  end

  # OR

  def rhyme_with(expected)
    simple_matcher do |given, matcher|
      matcher.description = &quot;rhyme with #{expected.inspect}&quot;
      matcher.failure_message = &quot;expected #{given.inspect} to rhyme with #{expected.inspect}&quot;
      matcher.negative_failure_message = &quot;expected #{given.inspect} not to rhyme with #{expected.inspect}&quot;
      given.rhymes_with? expected
    end
  end

  describe &quot;pecan&quot; do
    it &quot;should rhyme with 'be gone'&quot; do
      nut = &quot;pecan&quot;
      nut.extend Rhymer
      nut.should rhyme_with(&quot;be gone&quot;)
    end
  end
</pre>
<p>
The resulting messages would <a href="Matchers.html#M000383">be</a>:
</p>
<pre>
  description:              rhyme with &quot;be gone&quot;
  failure_message:          expected &quot;pecan&quot; to rhyme with &quot;be gone&quot;
  negative failure_message: expected &quot;pecan&quot; not to rhyme with &quot;be gone&quot;
</pre>
<h2>Wrapped <a href="Expectations.html">Expectations</a></h2>
<p>
Because errors will bubble up, it is possible to wrap other expectations in
a <a href="Matchers/SimpleMatcher.html">SimpleMatcher</a>.
</p>
<pre>
  def be_even
    simple_matcher(&quot;an even number&quot;) { |given| (given % 2).should == 0 }
  end
</pre>
<p>
BE VERY CAREFUL when you do this. Only use wrapped expectations for
matchers that will always <a href="Matchers.html#M000383">be</a> used in
only the positive (<tt>should</tt>) or negative (<tt>should_not</tt>), but
not both. The reason is that is you wrap a <tt>should</tt> and call the
wrapper with <tt>should_not</tt>, the correct result (the <tt>should</tt>
failing), will fail when you want it to pass.
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000372-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000372-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/rspec/lib/spec/matchers/simple_matcher.rb, line 128</span>
128:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">simple_matcher</span>(<span class="ruby-identifier">description</span>=<span class="ruby-keyword kw">nil</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">match_block</span>)
129:       <span class="ruby-constant">SimpleMatcher</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">description</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">match_block</span>)
130:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000374" class="method-detail">
        <a name="M000374"></a>

        <div class="method-heading">
          <a href="#M000374" class="method-signature">
          <span class="method-name">should throw_symbol()<br />
should throw_symbol(:sym)<br />
should_not throw_symbol()<br />
should_not throw_symbol(:sym)<br />
</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Given a <a href="../Symbol.html">Symbol</a> argument, matches if the given
proc throws the specified <a href="../Symbol.html">Symbol</a>.
</p>
<p>
Given no argument, matches if a proc throws any <a
href="../Symbol.html">Symbol</a>.
</p>
<h2>Examples</h2>
<pre>
  lambda { do_something_risky }.should throw_symbol
  lambda { do_something_risky }.should throw_symbol(:that_was_risky)

  lambda { do_something_risky }.should_not throw_symbol
  lambda { do_something_risky }.should_not throw_symbol(:that_was_risky)
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000374-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000374-source">
<pre>
    <span class="ruby-comment cmt"># File vendor/plugins/rspec/lib/spec/matchers/throw_symbol.rb, line 70</span>
70:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">throw_symbol</span>(<span class="ruby-identifier">sym</span>=<span class="ruby-keyword kw">nil</span>)
71:       <span class="ruby-constant">Matchers</span><span class="ruby-operator">::</span><span class="ruby-constant">ThrowSymbol</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">sym</span>)
72:     <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>


    </div>


  </div>


<div id="validator-badges">
  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>

</body>
</html>